package fr.mywiki.business.entry.meta;

import java.text.ParseException;
import java.util.Locale;

import org.jdom.Element;

/** Each type of property implements this interface. */
public interface DataType {
	/** Returns the unique name (key) that identifies the data type. */
	public String getTypeName();

	/**
	 * Returns the key that enables the display of a name from the resource
	 * bundle.
	 */
	public String getDisplayKey();

	/**
	 * This method is able to check if something entered by the user (the
	 * <tt>value</tt> object) is valid according to the specifications of the
	 * property (contained in the <code>DataType</code> object). It returns
	 * <tt>null</tt> if no error was detected, the type of error otherwise (a
	 * key to access the correct message).
	 * 
	 * @param value
	 *          the value entered by the user.
	 * @return <tt>null</tt> if no error, the error key otherwise.
	 */
	public String checkValue(Object value);
	
	/**
	 * Describes the created datatype (its specifications particularly). Can be
	 * displayed on client-end side more easily than a <code>toString()</code>
	 * method, more reserved to developpers. Should rather be a short description.
	 * 
	 * @param locale
	 *          the locale in which it has to be displayed.
	 * @return a <code>String</code> object.
	 */
	public String describe(Locale locale);
	
	/**
	 * Completes the xml description of a <code>Property</code> object by
	 * joining the specifications of the datatype under the form of attributes.
	 * 
	 * @param elt a <code>Element</code> object, modified by this method.
	 */
	public void describeXml(Element elt);
	
	/**
	 * Completes the current object with the specifications contained in the XML
	 * <code>Element</code> given in parameter.
	 * 
	 * @param elt
	 */
	public void fillFromXml(Element elt);
	
	/**
	 * Returns the expected value of the object coded as the String entered in
	 * parameter.
	 * 
	 * @param strVal
	 *          a <code>String</code> entered by the user destined to represent
	 *          an object of a specific data type.
	 * @return an <code>Object</code>.
	 * @throws ParseException
	 *           if the String value was not correct.
	 */
	public Object getValue(String strVal) throws ParseException;
}
